This is a small guide for Hextracker(version 0.825).
====================================================

Please remember that this program will remain BETA for ever !
The author refuses any blaming for any errors detected !
This program MUST not be sold as it was given by the author to the Atari comunity.
This program should work both in colour and mono mode with a 512Kb STF/E but 1MB or more is better.
It can handle from 1 up to 16 voices but up to 8 will be better.
The user has full volume and pitch control(3 octaves) for each voice.


Now to the buttons :) !

EXIT: left click on top left corner (DON'T FORGET TO SAVE !!!!!!!).

POSITION: selects the song position from 0 to END POSITION
- arrow up: goes to position +1 or +$10 up to END POSITION
- arrow down: goes to position -1 or -$10 down to 0
- digits: selects the increments/decrements 1 or $10

PATTERN: selects the pattern for the song position from 0 to $FF
- arrow up: increase the pattern number by 1 or $10
- arrow down: decrease the pattern number by 1 or $10
- digits: selects the increments/decrements 1 or $10

END POSiTION: sets the song length from 0(1 position) to $FF(256 positions)
- arrow up: increase the end position number by 1 or $10
- arrow down: decrease the end position number by 1 or $10
- digits: selects the increments/decrements 1 or $10

RESTART POS: selects the song restart position from 0 to END POSITION
- arrow up: goes to position +1 or +$10 up to END POSITION
- arrow down: goes to position -1 or -$10 down to 0
- digits: selects the increments/decrements 1 or $10

SAMPLE: selects the current SAMPLE from 1 to $FF
- arrow up: increase the sample number by 1 or $10
- arrow down: decrease the sample number by 1 or $10
- digits: selects the increments/decrements 1 or $10

LENGTH: adjusts the sample length decreasing it at the start or at the end
- left arrow down: decrease the sample length at the start by 1, $10 ... $100000 dwon to 0
- right arrow down: decrease the sample length at the end by 1, $10 ... $100000 dwon to 0
- digits: selects the decrements 1, $10, $100, $1000, $10000 or $100000

REPSTRT: sets the loop start position from 0 to sample length
- arrow up: increase the loop start position by 1 or $10 ... $100000 up to sample length
- arrow down: decrease the loop start position by 1 or $10 ... $100000 down to 0
- digits: selects the increments/decrements 1, $10, $100, $1000, $10000 or $100000

LOOPLEN: sets the loop length from 0 to sample length
- arrow up: increase the loop length by 1 or $10 ... $100000 up to sample length - loop start
- arrow down: decrease the loop length by 1 or $10 ... $100000 down to 0
- digits: selects the increments/decrements 1, $10, $100, $1000, $10000 or $100000

VOLUME: sets the default volume for the sample from 0 to $40
- arrow up: increase the sample default volume by 1 or $10 up to $40
- arrow down: decrease the sample number by 1 or $10 down to 0
- digits: selects the increments/decrements 1 or $10

SONGNAME: click on the name/spaces to edit
SAMPLENAME: click on the name/spaces to edit
TEXT EDITOR:
- mouse selects edit position
- insert toggles insert/replace mode
- arrows, backspace and delete allowed
- return/enter ends editor

SONG: info size in bytes of the MOD
MEMORY: info size in bytes of the memory left
DISK: click on it to get the size available on the working disk

MESSAGE: information that may sometimes wait for space or editor key when the mouse pointer is hidden

NCHAN: set the number of voices from 1 to 16 (value in decimal)
- arrow up: increase the number os voices by 1 up to 16
- arrow down: decrease the number of voices by 1 down to 0

HEXTRACKER: shows some info about the utility

PLAY: plays the song in TRACK mode ! (numeric pad toggles voices / enter sets all)
Space stops.
Play can also automaticaly stop if:
- there is not enough memory
- there is no CPU time left
- a song error is found like non existing pattern or sample
- ...

PATTERN: sets Pattern mode that will keep playing the same pattern

RECORD: will allow pressed keys to be stored in the current voice in the MOD data as if a sample was played while the MOD is played

EDIT: allows pattern data to be edited manually

The tone keys support 3 octaves:
- 12 keys from TAB to the right
- 12 keys from CONTROL to the right
- 12 keys from LEFT SHIFT to the right

PRINT: will print the MOD

FSAMPL: sets the base frequency for all samples.
Default value for MOD is 9855 Hz in decimal that should be the sampling rate for a D#2
or it can be 8287 Hz for a C-2.
If you sample a A-2 then you should sample it at 9855*2^(6/12) = 13937 Hz.
The A is 6 steps after the D#2 and 1 octave has 12 steps.
If you start from C then we have 9 steps: 8287*2^(9/12) = 13937 Hz.
If we have a B-3 then from D#2, we have 20 steps: 9855*2^(20/12) = 31288 Hz.
Going to octave 1, the rule is the same but with negative steps.
This allows to have higher frequency (and better quality) samples.
- arrow up: increase the samples frequency by 1, 10, 100, 1000, 10000 up to 65535 Hz
- arrow down: decrease the samples frequency by 1, 10, 100, 1000, 10000 down to 100 Hz (be careful !)

OUTPUT: toggles the OUTPUT and DISK panels

OUTPUT panel:
- Arrows select output type (all except YM and STE were not tested with the HW)
  STE tested with Steem 3.2 !
- Arrows select replay frequency (if it is too much the player will stop !)
- Arrows set the Volume/Quality factor
- DIST option will calculate the optimum V/Q factor after the complete MOD was played once.
  That value is different for mono and stereo mode.
  That value is inicialized to half of the number of voices (4 voices -> 2.0)
- DATA DIST option when selected displays the pattern data while playing
- VU METER option when selected displays some VU meters up to 8 channels (please notice how looped samples persist ...)
- DIGISCOPE option will display the graphical pic of the data sent to the output device
  (maximum 352 dots => 17.5 KHz (more frequency will lead to same amount of dots))
- SAMPL: selects the sample type to be loaded/saved signed or unsigned

DISK panel:
- LOAD SAMP: loads sample
- SAVE SAMP: saves sample
- LOAD MOD: loads MOD (several formats can be imported (TCB, OKT, Protracker(s), STE Oktalyser, Fast Tracker / Take Tracker))
- SAVE MOD: saves the MOD in Hextracker format
- LOAD SONG: loads the song part and looks for the samples in the same directory
- SAVE SONG: saves the song part
- DEL FILE: delete file

TRACK/SAMPL: toggles TRACK and SAMPL mode that will allow a better sample size adjustment

PATTERN DATA:
- left top corner: select pattern
- Arrows up, down, left, right to move around
- Digits, A, B, C, D, E, F and delete to edit
- Crotchets: turn voice on/off
- F1: marks start of block
- F2: marks end of block
- F3: copy marked block for the voice where the cursor is present
- F4: copy marked block from the voice where the cursor is to the marked voice
- F5: copy marked block from the voice where cursor is to all voices
- F6: copy marked block for all voices
- F7: copies the marked block from the current pattern to the marked pattern(+F5) for all voices
- F8: deletes tone + effects
- F9: - $10 positions
- F10: + $10 positions
- +F1: mark voice
- +F2: switch marked voice with the one below cursor for all patterns
- +F3: overwrite marked voice with the one below cursor for all patterns
- +F4: deletes the contents of 1 voice for all patterns
- +F5: marks a pattern
- +F6: clears block marked by F1 and F2 including limits but only on the used voice
- +F7: clears block marked by F1 and F2 including limits on all voices
- +F8: create pattern
- +F9: deletes a pattern
- +F10: deletes a sample

Playing will stop if an error is detected like no sample, no pattern ...

Known issues:
=============
- TCB Tracker and OKTalyser formats may be not fully read due to lack of documentation;
- Extended octaves are not supported and lead to a crash so the support of Take tracker and Fast tracker files is limited;
- BPM, finetune and update funk commands are ignored and not supported;
- Mod loading does not check for all error possibilities in the file;
- Some issues with memory not restored with load/save sample;
- Config.inf file is for a QWERTY keyboard !!! (128 bytes without shift + 128 bytes with)
- Most of the tests have been done in MONO mode: STEREO is even more beta
- STE output is also very beta as i do not own one and it was tested with Steem
- Mixing routs have been built for STF so for STE Lance's player is much better for 4 voices MODs

Have fun,
Paulo.



Annex 1:

Minimum replay frequencies possible (in MONO with YM2149):

Tone keys: 30720

/* Nothing */
16 -  9170
14 - 10413
12 - 12047
10 - 13963
 8 - 16605
 6 - 19819
 4 - 26713

/* Worse (Dist + Data - VU + Digiscope) */
16 -  4726
14 -  5296
12 -  6083
10 -  6981
 8 -  8084
 6 - 10778
 4 - 14288

/* Just Dist */
16 -  8653
14 -  9752
12 - 10971
10 - 12538
 8 - 14985
 6 - 17554
 4 - 22341

/* Just Scrolling Data */
16 -  5688
14 -  6467
12 -  7492
10 -  8777
 8 - 10593
 6 - 14628
 4 - 20480

/* Dist + Scrolling Data */
16 -  5251
14 -  6023
12 -  6903
10 -  8084
 8 -  9452
 6 - 12934
 4 - 17554

/* Just VU */
16 -  7585
14 -  8777
12 - 10240
10 - 12047
 8 - 14628
 6 - 18618
 4 - 24576

/* Just Digiscope */
16 -  8192
14 -  9170
12 - 10413
10 - 11815
 8 - 13963
 6 - 16605
 4 - 21186

/* Data + VU */
16 -  6083
14 -  7062
12 -  8302
10 -  9909
 8 - 12047
 6 - 16168
 4 - 22341

/* Data + Disgiscope */
16 -  5036
14 -  5715
12 -  6536
10 -  7585
 8 -  8904
 6 - 11815
 4 - 16168

/* VU + Digiscope */
16 -  6751
14 -  7777
12 -  8904
10 - 10413
 8 - 12288
 6 - 14985
 4 - 19200

/* Data + Digiscope + VU */
16 -  5437
14 -  6206
12 -  7228
10 -  8533
 8 - 10072
 6 - 13072
 4 - 17066


STE (with nothing):
- 4 voices at 50KHz
- 6 voices at 25 KHz
- 8 voices 25KHz in mono and for most in stereo
- 12 voices at 12.5 KHz in mono or stereo and in some cases 16.7 KHz
- 16 voices 10 KHz in mono (some at 12.5) and also for most in stereo

STE Stereo (worst case):
- 4 voices at 12.5 KHz
- 6 voices at 8.34 KHz
- 8 voices at 6.25 KHz
- 12 voices at 5 KHz
- 16 voices at 4.17 KHz

STE Mono (worst case):
- 4 voices at 16.7 KHz
- 6 voices at 12.5 KHz
- 8 voices at 10 KHz
- 12 voices at 6.25 KHz
- 16 voices at 5 KHz

STE Stereo (Data + Disgiscope):
- 4 voices at 25 KHz
- 6 voices at 12.5 KHz
- 8 voices at 8.34 KHz
- 12 voices at 6.25 KHz
- 16 voices at 4.17 KHz

STE Mono (Data + Disgiscope):
- 4 voices at 25 KHz
- 6 voices at 12.5 KHz
- 8 voices at 10 KHz
- 12 voices at 7.15 KHz
- 16 voices at 5.5 KHz

STE Stereo (Data only):
- 4 voices at 25 KHz
- 6 voices at 16.7 KHz
- 8 voices at 12.5 KHz
- 12 voices at 8.34 KHz
- 16 voices at 6.25 KHz

STE Mono (Data only):
- 4 voices at 50 KHz
- 6 voices at 16.7 KHz
- 8 voices at 12.5 KHz
- 12 voices at 8.34 KHz
- 16 voices at 6.25 KHz


Emulators note:
Steem 3.2 at 32MHz allows 16 voices mono/stereo on STE mode at 50 KHz with all.
This is especially nice to find the correct VQs ...


Annex2: Hectracker file format

***************************************************************************
*	HEXTRACKER FORMAT
*
* $00		'HEXTRACK'			8 bytes
* $08		MOD NAME			20 bytes
* $1C@7...4	RESERVED FOR FUTURE USE		4 bits
* $1C@3...0	NUMBER OF VOICES - 1		4 bits
* $1D		VQ FACTOR			1 byte
* $1E		PATTERN LIST LENGTH(PLL) - 1	1 byte
* $1F		RESTART PATTERN LIST INDEX	1 byte
* $20		PATTERN LIST			PLL (or +1) to even number
* $20+PLL	PATTERNS CONTROL BITMAP		256 bits
* $40+PLL	EXISTING PATTERNS PACKED	variable
* variable	SAMPLES BASE FREQUENCY		2 bytes
* variable	SAMPLES CONTROL BITMAP		256 bits
* variable	SAMPLES DESCRIPTORS		32 bytes each
* variable	SAMPLES				variable
***************************************************************************
VQ $10 => no amplification , $18 amplify 1.5 times, $20 amplifly  2 times ...
Bitmaps 0 pattern/sample not included   1 pattern/sample included
SAMPLES BASE FREQUENCY: 9855 for default Amiga/Protracker for other value the samples have to be played x/9855 times faster
SAMPLES DESCRIPTORS:
		$00		sample name		22 bytes
		$16		size			3 bytes
		$19		repeat start		3 bytes
		$1C		loop size		3 bytes
		$1F		volume(0-64($40))	1 byte

Packed pattern data:
====================
First byte bits 7 and 6:

	00	=> Read 4 bytes like UNPACKED data
		Byte 1: Tone    0 -> 36 ( 0: no tone 1: B-3 ... 36: C-1 )
		Byte 2: Sample number
		Byte 3: Effect number (0 -> F)
		Byte 4: Effect data (0 -> FF)

		Bytes 3 and 4: $0xxx where xxx is equal to Protracker data
		Examples:
		- effect 4(vibrato) and data $A1 => $04A1
		- effect $E6(loop) and data 0 (set loop) => $0E60

	01	=> Read 2 bytes and clear bit 6:
		Byte 1: Tone    0 -> 36 ( 0: no tone 1: B-3 ... 36: C-1 )
		Byte 2: Sample number
		Effect number = 0
		Effect data = 00

	10	=> Read 2 bytes and clear bit 7:
		Byte 1: Effect number (0 -> F)
		Byte 2: Effect data (0 -> FF)
		Tone = 0;
		Sample number = 0

	11	=> Read 1 byte and clear bits 6 and 7:
		Byte 1: Tone    0 -> 36 ( 0: no tone 1: B-3 ... 36: C-1 )
		Sample number = 0
		Effect number = 0
		Effect data = 00



****	Get and unpack data

	moveq	#0,d0
	moveq	#0,d1
*	moveq	#0,d2							UPK
*	move.b	(a1)+,d0						UPK
*	move.b	(a1)+,d1						UPK
*	move.b	(a1)+,batribute(a3)					UPK
*	move.b	(a1)+,d2						UPK
	moveq	#6,d2							PCK
	move.b	(a1)+,d0			1st byte		PCK
	bpl.s	toca06				positive ?  yes	%0X	PCK
	and.b	#$7F,d0				7 bits only	%1X	PCK
	bclr	d2,d0				test and clear bit 6	PCK
	bne.s	toca07				set ? yes	%11	PCK
	move.b	d0,batribute(a3)				%10	PCK
	move.b	(a1)+,d2						PCK
	moveq	#0,d0							PCK
	bra.s	toca09							PCK
toca06:
	move.b	(a1)+,d1					%0X	PCK
	bclr	d2,d0				test and clear bit 6	PCK
	beq.s	toca08				set ? no	%01	PCK
toca07:
	moveq	#0,d2							PCK
	clr.b	batribute(a3)						PCK
	bra.s	toca09							PCK
toca08:
	move.b	(a1)+,batribute(a3)				%00	PCK
	move.b	(a1)+,d2						PCK
toca09:


